Inside Macintosh: Sound
| Previous | Chapter contents | Chapter top | Section top | Next |
To write a sound component, you might need to define routines that manage the loading, configuration, and unloading of your sound component:
After the Sound Manager opens your sound component, it attempts to add your sound component to a sound component chain. Thereafter, the Sound Manager calls your component's SoundComponentInitOutputDevice function to give you an opportunity to set default values for any associated hardware and to perform any hardware-specific operations.
A sound output device component must implement the SoundComponentInitOutputDevice function. The Sound Manager calls this function to allow a sound output device component to configure any associated hardware devices.
pascal ComponentResult SoundComponentInitOutputDevice
(ComponentInstance ti, long
actions);
Your SoundComponentInitOutputDevice function is called by the Sound Manager at noninterrupt time to allow your sound output device component to perform any hardware-specific initialization. You should perform any necessary initialization that was not already performed in your OpenComponent function. Note that your OpenComponent function cannot assume that the appropriate hardware is available. As a result, the Sound Manager calls your SoundComponentInitOutputDevice function when it is safe to communicate with your audio hardware. You can call the OpenMixerSoundComponent function to create a single sound component chain.
Your SoundComponentInitOutputDevice function is always called at noninterrupt time. All other component-defined routines might be called at interrupt time. Accordingly, your SoundComponentInitOutputDevice function should handle any remaining memory allocation needed by your component and it should lock down any relocatable blocks your component will access.
Your SoundComponentInitOutputDevice function should return noErr if successful or an appropriate result code otherwise.
See Listing 7 for a sample SoundComponentInitOutputDevice function.
A sound component can implement the SoundComponentSetSource function. The Sound Manager calls this function to identify your component's source component.
pascal ComponentResult SoundComponentSetSource
(ComponentInstance ti,
SoundSource sourceID,
ComponentInstance source);
Your SoundComponentSetSource function is called by the Sound Manager to identify to your sound component the sound component that is its source. The source component is identified by the source parameter. Your component uses that information when it needs to obtain more data from its source (usually, by calling its SoundComponentGetSourceData function).
Because a sound output device component is always connected directly to one or more instances of the Apple Mixer, the SoundComponentSetSource function needs to be implemented only by utility components (that is, components that perform modifications on sound data). Utility components are linked together into a chain of sound components, each link of which has only one input source. As a result, a utility component can usually ignore the sourceID parameter passed to it.
A sound component can implement the SoundComponentGetSource function. The Sound Manager calls this function to determine your component's source component.
pascal ComponentResult SoundComponentGetSource
(ComponentInstance ti,
SoundSource sourceID,
ComponentInstance *source);
Your SoundComponentGetSource function is called by the Sound Manager to retrieve your component's source component instance. Your component should return, in the source parameter, the component instance of your component's source. This should be the source component instance your component was passed when the Sound Manager called your SoundComponentSetSource function.
In general, all sound components have sources, except for the source at the beginning of the source component chain. In the unlikely event that your component does not have a source, you should return nil in the source parameter. A sound output device component is always connected directly to an instance of the Apple Mixer. Accordingly, a sound output device component should return a component instance of the Apple Mixer in the source parameter and a source ID in the sourceID parameter. A utility component can ignore the sourceID parameter.
A utility component must implement the SoundComponentGetSourceData function. A sound output device component calls this function on its source component when it needs more data.
pascal ComponentResult SoundComponentGetSourceData
(ComponentInstance ti,
SoundComponentDataPtr
*sourceData);
Your SoundComponentGetSourceData function is called when the sound component immediately following your sound component in the sound component chain needs more data. Your function should generate a new block of audio data, fill out a sound component data record describing the format and location of that data, and then return the address of that record in the sourceData parameter.
Your SoundComponentGetSourceData function might itself need to get more data from its source component. To do this, call through to the source component's SoundComponentGetSourceData function. If your component cannot generate any more data, it should set the sampleCount field of the sound component data record to 0 and return noErr .
Sound output device components do not need to implement this function, but all utility components must implement it.
A sound output device component can call the SoundComponentSetOutput function of the Apple Mixer to indicate the type of data it expects to receive.
pascal ComponentResult SoundComponentSetOutput
(ComponentInstance ti,
SoundComponentDataPtr requested,
SoundComponentDataPtr *actual);
The Apple Mixer's SoundComponentSetOutput function can be called by a sound output device component to specify the kind of audio data the output device component wants to receive. The Apple Mixer uses that information to determine the type of sound component chain it needs to construct in order to deliver that kind of audio data to your sound output device component. For example, if your sound output device is able to accept 16-bit samples, the Sound Manager doesn't need to convert 16-bit audio data into 8-bit data.
The following lines of code illustrate how the sound output device component for the Apple Sound Chip might call Apple Mixer's SoundComponentSetOutput function:
myDataRec.flags = 0; /*ignored here*/
myDataRec.format = kOffsetBinary; /*ASC needs offset binary*/
myDataRec.sampleRate = rate22khz; /*ASC needs 22 kHz samples*/
myDataRec.sampleSize = 8; /*ASC needs 8-bit data*/
myDataRec.numChannels = 2; /*ASC can do stereo*/
myDataRec.sampleCount = 1024; /*ASC uses a 1K FIFO*/
myErr = SoundComponentSetOutput(mySource, &myDataRec, &myActual);
In general, however, a sound output device component shouldn't need to call the Apple Mixer's SoundComponentSetOutput function. Instead, it can indicate the type of data it expects to receive when it calls the OpenMixerSoundComponent function. The SoundComponentSetOutput function is intended for sophisticated sound output device components that might want to reinitialize the Apple Mixer.
Only the Apple Mixer component needs to implement this function.
| Previous | Chapter contents | Chapter top | Section top | Next |